---
title: 모델 컨텍스트 프로토콜 (MCP)
description: Learn how to utilize MCP servers as tools
---

import { Code } from '@astrojs/starlight/components';
import hostedAgentExample from '../../../../../../examples/docs/mcp/hostedAgent.ts?raw';
import hostedExample from '../../../../../../examples/docs/mcp/hosted.ts?raw';
import hostedStreamExample from '../../../../../../examples/docs/mcp/hostedStream.ts?raw';
import hostedHITLExample from '../../../../../../examples/docs/mcp/hostedHITL.ts?raw';
import hostedConnectorExample from '../../../../../../examples/docs/mcp/hostedConnector.ts?raw';
import streamableHttpExample from '../../../../../../examples/docs/mcp/streamableHttp.ts?raw';
import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw';
import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw';

[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io)은 애플리케이션이 LLM에 도구와 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP 문서에서 인용:

> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP를 AI 애플리케이션용 USB‑C 포트라고 생각해 보세요. USB‑C가 다양한 주변기기와 액세서리에 기기를 연결하는 표준 방식을 제공하듯, MCP는 AI 모델을 서로 다른 데이터 소스와 도구에 연결하는 표준 방식을 제공합니다.

이 SDK가 지원하는 MCP 서버 유형은 세 가지입니다:

1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp)가 도구로 사용하는 원격 MCP 서버
2. **Streamable HTTP MCP servers** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)를 구현한 로컬 또는 원격 서버
3. **Stdio MCP servers** – 표준 입출력을 통해 접근하는 서버(가장 간단한 옵션)

사용 사례에 따라 서버 유형을 선택하세요:

| 필요한 것                                                                 | 권장 옵션               |
| ------------------------------------------------------------------------- | ----------------------- |
| 공개적으로 접근 가능한 원격 서버를 기본 OpenAI Responses 모델과 함께 호출 | **1. Hosted MCP tools** |
| 공개적으로 접근 가능한 원격 서버를 사용하지만 도구 호출을 로컬에서 트리거 | **2. Streamable HTTP**  |
| 로컬에서 실행 중인 Streamable HTTP 서버 사용                              | **2. Streamable HTTP**  |
| OpenAI Responses가 아닌 모델로 모든 Streamable HTTP 서버 사용             | **2. Streamable HTTP**  |
| 표준 I/O 프로토콜만 지원하는 로컬 MCP 서버 사용                           | **3. Stdio**            |

## 1. Hosted MCP server tools

호스티드 툴은 전체 왕복 과정을 모델 내부로 밀어 넣습니다. 코드가 MCP 서버를 호출하는 대신, OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다.

다음은 호스티드 MCP 툴을 사용하는 가장 간단한 예시입니다. 원격 MCP 서버의 레이블과 URL을 `hostedMcpTool` 유틸리티 함수에 전달할 수 있으며, 이는 호스티드 MCP 서버 도구를 생성할 때 유용합니다.

<Code lang="typescript" code={hostedAgentExample} title="hostedAgent.ts" />

그런 다음 `run` 함수(또는 커스텀 `Runner` 인스턴스의 `run` 메서드)로 에이전트를 실행할 수 있습니다:

<Code
  lang="typescript"
  code={hostedExample}
  title="Run with hosted MCP tools"
/>

증분 MCP 결과를 스트리밍하려면 `Agent`를 실행할 때 `stream: true`를 전달하세요:

<Code
  lang="typescript"
  code={hostedStreamExample}
  title="Run with hosted MCP tools (streaming)"
/>

#### 선택적 승인 흐름

민감한 작업의 경우 개별 도구 호출에 대해 사람의 승인을 요구할 수 있습니다. `requireApproval: 'always'` 또는 도구 이름을 `'never'`/`'always'`에 매핑하는 세분화된 객체를 전달하세요.

도구 호출의 안전성을 프로그램적으로 판단할 수 있다면 [`onApproval` 콜백](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts)을 사용해 도구 호출을 승인하거나 거부할 수 있습니다. 사람의 승인이 필요한 경우 로컬 함수 도구와 동일하게 `interruptions`를 사용하는 동일한 [휴먼 인 더 루프 (HITL)](/openai-agents-js/ko/guides/human-in-the-loop/) 접근 방식을 사용할 수 있습니다.

<Code
  lang="typescript"
  code={hostedHITLExample}
  title="Human in the loop with hosted MCP tools"
/>

### 커넥터 기반 호스티드 서버

호스티드 MCP는 OpenAI 커넥터도 지원합니다. `serverUrl`을 제공하는 대신 커넥터의 `connectorId`와 `authorization` 토큰을 전달하세요. 그러면 Responses API가 인증을 처리하고 호스티드 MCP 인터페이스를 통해 커넥터의 도구를 노출합니다.

<Code
  lang="typescript"
  code={hostedConnectorExample}
  title="Connector-backed hosted MCP tool"
/>

이 예시에서 `GOOGLE_CALENDAR_AUTHORIZATION` 환경 변수에는 Google OAuth Playground에서 얻은 OAuth 토큰이 저장되어 있으며, 이는 커넥터 기반 서버가 Calendar API를 호출하도록 권한을 부여합니다. 스트리밍도 함께 보여주는 실행 가능한 샘플은 [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors)를 참조하세요.

완전한 동작 샘플(Hosted tools/Streamable HTTP/stdio + Streaming, HITL, onApproval)은 GitHub 리포지토리의 [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp)에 있습니다.

## 2. Streamable HTTP MCP servers

에이전트가 로컬 또는 원격의 Streamable HTTP MCP 서버와 직접 통신하는 경우, 서버의 `url`, `name` 및 선택적 설정을 사용해 `MCPServerStreamableHttp`를 인스턴스화하세요:

<Code
  lang="typescript"
  code={streamableHttpExample}
  title="Run with Streamable HTTP MCP servers"
/>

생성자는 `authProvider`, `requestInit`, `fetch`, `reconnectionOptions`, `sessionId`와 같은 추가 MCP TypeScript‑SDK 옵션도 허용합니다. 자세한 내용은 [MCP TypeScript SDK 리포지토리](https://github.com/modelcontextprotocol/typescript-sdk)와 문서를 참고하세요.

## 3. Stdio MCP servers

표준 I/O만 노출하는 서버의 경우 `fullCommand`로 `MCPServerStdio`를 인스턴스화하세요:

<Code
  lang="typescript"
  code={stdioExample}
  title="Run with Stdio MCP servers"
/>

## 알아두면 좋은 사항

**Streamable HTTP** 및 **Stdio** 서버의 경우, `Agent`가 실행될 때마다 사용 가능한 도구를 확인하기 위해 `list_tools()`를 호출할 수 있습니다. 이 왕복 과정은 특히 원격 서버에서 지연을 유발할 수 있으므로, `MCPServerStdio` 또는 `MCPServerStreamableHttp`에 `cacheToolsList: true`를 전달하여 결과를 메모리에 캐시할 수 있습니다.

도구 목록이 변경되지 않는다고 확신할 때만 활성화하세요. 나중에 캐시를 무효화하려면 서버 인스턴스에서 `invalidateToolsCache()`를 호출하세요.

### 도구 필터링

`createMCPToolStaticFilter`를 통한 정적 필터 또는 커스텀 함수를 전달하여 각 서버에서 노출되는 도구를 제한할 수 있습니다. 다음은 두 가지 접근 방식을 모두 보여주는 결합 예시입니다:

<Code lang="typescript" code={toolFilterExample} title="Tool filtering" />

## 추가 자료

- [Model Context Protocol](https://modelcontextprotocol.io/) – 공식 명세
- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 위에서 언급한 실행 가능한 데모
